ATOM Documentation

Canvas API Reference

**Version:** 1.0.0

**Last Updated:** 2026-02-16

**Phase:** 39-02 - Canvas Components Port

Overview

The Canvas API provides endpoints for managing canvas sessions, context, recording, browser automation, terminal execution, action proposals, and marketplace components.

**Base URL:** https://api.atomagentos.com

**Authentication:** All endpoints require JWT token via Authorization: Bearer <token> header or tenant_id parameter.

**Tenant Isolation:** All endpoints enforce tenant isolation via tenant_id parameter or extracted from user context.

---

Table of Contents

1. Canvas Context API
2. Canvas Terminal API
3. Canvas Browser API
4. Canvas Recording API
5. Canvas Action Proposals API
6. Canvas Marketplace API
7. Canvas Skills API
8. Integration Canvas API
9. WebSocket Connections
10. Error Codes
11. Governance Rules

---

Canvas Context API

Manage canvas context for agent learning and memory.

Create Canvas Context

**POST** /api/canvas/{canvas_id}/context

Creates a new canvas context for agent memory.

**Request Body:**

{
  "canvas_type": "terminal|browser|desktop",
  "agent_id": "optional-agent-id",
  "initial_state": {
    "working_directory": "/tmp",
    "environment": {}
  }
}

**Response:**

{
  "context_id": "ctx-abc123",
  "canvas_id": "canvas-xyz",
  "canvas_type": "terminal",
  "created_at": "2026-02-16T00:00:00Z"
}

**Governance:**

• All maturity levels: Allowed
• Tenant isolation: Enforced

---

Get Canvas Context

**GET** /api/canvas/{canvas_id}/context

Retrieve canvas context snapshot including recent actions and corrections.

**Response:**

{
  "context_id": "ctx-abc123",
  "canvas_id": "canvas-xyz",
  "current_state": {
    "working_directory": "/home/user",
    "last_command": "ls"
  },
  "session_history": [
    {
      "type": "execute_command",
      "command": "ls",
      "timestamp": "2026-02-16T00:00:00Z"
    }
  ],
  "user_corrections": [],
  "user_preferences": {
    "auto_approve_patterns": ["npm install"],
    "rejection_patterns": ["rm -rf"]
  }
}

**Governance:**

• All maturity levels: Allowed (read-only)
• Tenant isolation: Enforced

---

Update Canvas State

**PUT** /api/canvas/{canvas_id}/context/state

Update current canvas state (e.g., terminal working directory, browser URL).

**Request Body:**

{
  "state_update": {
    "working_directory": "/new/path",
    "current_url": "https://example.com"
  }
}

**Response:**

{
  "message": "State updated",
  "current_state": {
    "working_directory": "/new/path"
  }
}

**Governance:**

• All maturity levels: Allowed
• Tenant isolation: Enforced

---

Canvas Terminal API

Create terminal sessions and execute commands.

Create Terminal Session

**POST** /api/canvas/{canvas_id}/terminal/create

Create a new terminal session for command execution.

**Request Body:**

{
  "working_directory": "/tmp",
  "environment": {
    "PATH": "/usr/bin:/bin"
  }
}

**Response:**

{
  "session_id": "term-abc123",
  "canvas_id": "canvas-xyz",
  "working_directory": "/tmp",
  "created_at": "2026-02-16T00:00:00Z"
}

**Governance:**

• Student/Intern: Requires approval
• Supervised: Allowed with monitoring
• Autonomous: Allowed

---

Execute Command

**POST** /api/canvas/{canvas_id}/terminal/{session_id}/execute

Execute a command in the terminal session.

**Request Body:**

{
  "command": "ls -la",
  "timeout": 30
}

**Response:**

{
  "exit_code": 0,
  "stdout": "total 0\ndrwxr-xr-x  2 user wheel  64 Feb 16 00:00 .",
  "stderr": "",
  "execution_time_ms": 45
}

**Governance:**

• Student: Read-only commands only (ls, pwd, cat)
• Intern: Safe commands only (no rm, mv, chmod)
• Supervised: Most commands allowed with monitoring
• Autonomous: All commands allowed

**Path Validation:**

• Student/Intern: No paths allowed
• Supervised: /tmp, home directory, .atom* paths only
• Autonomous: All paths except system directories

---

Canvas Browser API

Create browser sessions and automate web interactions.

Create Browser Session

**POST** /api/canvas/{canvas_id}/browser/create

Create a new browser session (cloud or desktop mode).

**Request Body:**

{
  "initial_url": "https://example.com",
  "execution_mode": "cloud|desktop"
}

**Response:**

{
  "session_id": "browser-abc123",
  "canvas_id": "canvas-xyz",
  "execution_mode": "cloud",
  "current_url": "https://example.com",
  "page_title": "Example Domain",
  "screenshot": "base64-encoded-image",
  "created_at": "2026-02-16T00:00:00Z"
}

**Governance:**

• All maturity levels: Allowed
• Desktop mode requires Tauri app

---

Navigate Browser

**POST** /api/canvas/{canvas_id}/browser/{session_id}/navigate

Navigate to a URL.

**Request Body:**

{
  "url": "https://example.com/page",
  "user_approved_sensitive": false
}

**Response:**

{
  "current_url": "https://example.com/page",
  "page_title": "Page Title",
  "screenshot": "base64-encoded-image"
}

**Governance:**

• All maturity levels: Allowed
• Sensitive sites (login, payment) require user approval

---

Execute Browser Action

**POST** /api/canvas/{canvas_id}/browser/{session_id}/execute

Execute a browser action (click, fill, scroll).

**Request Body:**

{
  "action": {
    "type": "click|fill|scroll|navigate",
    "selector": "#submit-button",
    "value": "test input"
  }
}

**Response:**

{
  "success": true,
  "screenshot": "base64-encoded-image",
  "execution_time_ms": 150
}

**Governance:**

• Student: View actions only (scroll, navigate)
• Intern: Safe actions (click, fill non-sensitive forms)
• Supervised: Most actions allowed
• Autonomous: All actions allowed

---

Canvas Recording API

Record and playback canvas sessions for governance and audit.

Start Recording

**POST** /api/canvas/{canvas_id}/recording/start

Start recording a canvas session.

**Request Body:**

{
  "canvas_type": "terminal",
  "agent_id": "agent-abc123",
  "session_name": "Data reconciliation task",
  "autonomous": false
}

**Response:**

{
  "recording_id": "rec-xyz789",
  "canvas_id": "canvas-xyz",
  "status": "recording",
  "started_at": "2026-02-16T00:00:00Z"
}

**Governance:**

• All maturity levels: Allowed
• Autonomous agent sessions should always be recorded

---

Record Event

**POST** /api/canvas/{canvas_id}/recording/{recording_id}/event

Record an event to the timeline.

**Request Body:**

{
  "event_type": "action_proposed|action_approved|action_executed|user_intervention",
  "event_data": {
    "action_id": "action-123",
    "description": "Execute data reconciliation"
  }
}

**Response:**

{
  "message": "Event recorded",
  "event_id": "evt-abc123",
  "timestamp": "2026-02-16T00:00:00Z"
}

**Event Types:**

• action_proposed - Agent proposed an action
• action_approved - User approved action
• action_rejected - User rejected action
• action_executing - Action is executing
• action_completed - Action completed successfully
• action_failed - Action failed
• user_intervention - User manually intervened

---

Stop Recording

**POST** /api/canvas/{canvas_id}/recording/{recording_id}/stop

Stop recording and finalize timeline.

**Request Body:**

{
  "status": "completed|failed|interrupted"
}

**Response:**

{
  "recording_id": "rec-xyz789",
  "status": "completed",
  "duration_seconds": 300,
  "event_count": 15,
  "stopped_at": "2026-02-16T00:05:00Z"
}

---

Canvas Action Proposals API

Enable agents to propose actions and wait for user approval (human-in-the-loop).

Propose Action

**POST** /api/canvas/{canvas_id}/propose-action

Agent proposes an action that requires user approval.

**Request Body:**

{
  "action_type": "execute_command|delete_files|send_email",
  "action_data": {
    "command": "rm -rf /tmp/test"
  },
  "description": "Remove test files",
  "reason": "Cleanup after testing",
  "reversible": false,
  "session_id": "session-abc123",
  "agent_id": "agent-xyz789"
}

**Response:**

{
  "action_id": "action-abc123",
  "status": "pending",
  "message": "Action proposed, awaiting approval",
  "created_at": "2026-02-16T00:00:00Z"
}

**Governance:**

• Checks AgentGovernanceService.can_perform_action()
• Student/Intern agents: Most actions require approval
• Supervised agents: High-risk actions require approval
• Autonomous agents: May still propose actions for transparency

---

Approve Action

**POST** /api/canvas/{canvas_id}/actions/{action_id}/approve

User approves proposed action (with optional modifications).

**Request Body:**

{
  "modified_data": {
    "command": "rm -rf /tmp/test --confirm"
  },
  "user_guidance": "Add confirmation flag for safety"
}

**Response:**

{
  "action_id": "action-abc123",
  "status": "approved",
  "message": "Action approved and executing",
  "approved_at": "2026-02-16T00:01:00Z"
}

---

Reject Action

**POST** /api/canvas/{canvas_id}/actions/{action_id}/reject

User rejects proposed action.

**Request Body:**

{
  "reason": "Too dangerous, use safer alternative"
}

**Response:**

{
  "action_id": "action-abc123",
  "status": "rejected",
  "reason": "Too dangerous, use safer alternative",
  "rejected_at": "2026-02-16T00:01:00Z"
}

---

Canvas Marketplace API

Browse, publish, install, and rate canvas components.

Browse Marketplace

**GET** /api/canvas-marketplace/components

Browse marketplace components with filtering and search.

**Query Parameters:**

• query (optional): Search query (searches name, description)
• category (optional): Filter by category
• tags (optional): Comma-separated tags
• component_type (optional): Filter by type (react, vue, html)
• min_price (optional): Minimum price
• max_price (optional): Maximum price
• is_free (optional): Show only free components
• sort_by (optional): Sort field (created_at, rating, installs, price)
• sort_order (optional): Sort order (asc, desc)
• limit (optional): Results per page (default: 50, max: 100)
• offset (optional): Pagination offset

**Response:**

{
  "components": [
    {
      "id": "comp-abc123",
      "name": "SmartChart",
      "description": "Interactive chart component",
      "category": "visualization",
      "component_type": "react",
      "version": "1.0.0",
      "price": 0.0,
      "rating": 4.5,
      "installs": 1234,
      "author": "AgentGPT",
      "created_at": "2026-02-16T00:00:00Z",
      "thumbnail_url": "https://..."
    }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}

**Authentication:** Not required (public marketplace)

---

Get Component Details

**GET** /api/canvas-marketplace/components/{id}

Get detailed information about a component.

**Response:**

{
  "id": "comp-abc123",
  "name": "SmartChart",
  "description": "Interactive chart component with real-time updates",
  "long_description": "Full component documentation...",
  "category": "visualization",
  "component_type": "react",
  "version": "1.0.0",
  "code": "export default function SmartChart(props) { ... }",
  "config_schema": {
    "type": "object",
    "properties": {
      "data": {"type": "array"},
      "chartType": {"type": "string", "enum": ["bar", "line", "pie"]}
    }
  },
  "dependencies": ["recharts", "lodash"],
  "price": 0.0,
  "license": "MIT",
  "tags": ["chart", "visualization", "react"],
  "author": "AgentGPT",
  "rating": 4.5,
  "rating_count": 42,
  "installs": 1234,
  "demo_url": "https://demo.example.com",
  "created_at": "2026-02-16T00:00:00Z"
}

---

Publish Component

**POST** /api/canvas-marketplace/components/publish

Publish a component to the marketplace.

**Request Body:**

{
  "component_id": "comp-abc123",
  "price": 0.0,
  "license": "MIT",
  "tags": ["chart", "visualization"]
}

**Response:**

{
  "component_id": "comp-abc123",
  "status": "published",
  "published_at": "2026-02-16T00:00:00Z",
  "marketplace_url": "https://atomagentos.com/marketplace/components/comp-abc123"
}

**Governance:**

• Requires marketplace permission (grant via /api/canvas-skills/marketplace/permission)
• Tenant isolation: Enforced
• Component must belong to tenant

---

Install Component

**POST** /api/canvas-marketplace/components/install

Install a component to tenant's canvases.

**Request Body:**

{
  "component_id": "comp-abc123",
  "canvas_id": "canvas-xyz",
  "config": {
    "chartType": "bar",
    "theme": "dark"
  }
}

**Response:**

{
  "installation_id": "inst-abc123",
  "component_id": "comp-abc123",
  "canvas_id": "canvas-xyz",
  "status": "installed",
  "skill_id": "skill-xyz789",
  "message": "Component and skill installed successfully",
  "installed_at": "2026-02-16T00:00:00Z"
}

**Note:** Installing a component automatically creates a paired skill for agent execution.

---

Rate Component

**POST** /api/canvas-marketplace/components/{id}/rate

Rate and review a component.

**Request Body:**

{
  "rating": 5,
  "review": "Excellent chart component, highly recommend!"
}

**Response:**

{
  "rating_id": "rating-abc123",
  "component_id": "comp-abc123",
  "rating": 5,
  "review": "Excellent chart component, highly recommend!",
  "created_at": "2026-02-16T00:00:00Z"
}

---

Canvas Skills API

Create components with paired skills and manage marketplace permissions.

Create Component with Skill

**POST** /api/canvas-skills/create

Agent creates a UI component and execution skill together.

**Request Body:**

{
  "name": "DataVisualizer",
  "description": "Visualizes data from API",
  "category": "visualization",
  "component_type": "react",
  "code": "export default function DataVisualizer(props) { ... }",
  "config_schema": {},
  "tags": ["chart", "api"],
  "skill_name": "visualize_data",
  "skill_description": "Fetches data from API and creates chart",
  "skill_type": "api",
  "skill_input_schema": {
    "api_url": {"type": "string"},
    "chart_type": {"type": "string"}
  },
  "skill_config": {
    "method": "GET",
    "headers": {}
  },
  "agent_id": "agent-abc123"
}

**Response:**

{
  "component_id": "comp-xyz789",
  "skill_id": "skill-abc123",
  "status": "created",
  "message": "Component and skill created successfully",
  "created_at": "2026-02-16T00:00:00Z"
}

**Governance:**

• Agent must have permission to create skills
• Tenant isolation: Enforced
• Component automatically linked to skill

---

Request Marketplace Permission

**POST** /api/canvas-skills/marketplace/permission

Grant permission to submit component to marketplace (one-time approval).

**Request Body:**

{
  "component_id": "comp-xyz789",
  "price": 9.99,
  "license": "MIT"
}

**Response:**

{
  "component_id": "comp-xyz789",
  "permission_granted": true,
  "can_submit_to_marketplace": true,
  "granted_at": "2026-02-16T00:00:00Z"
}

**Note:** This is a one-time permission per component. After granted, component can be submitted to marketplace.

---

Submit to Marketplace

**POST** /api/canvas-skills/marketplace/submit

Submit component to marketplace (requires prior permission).

**Request Body:**

{
  "component_id": "comp-xyz789",
  "tags": ["chart", "visualization", "api"]
}

**Response:**

{
  "component_id": "comp-xyz789",
  "status": "submitted",
  "submitted_at": "2026-02-16T00:00:00Z",
  "marketplace_url": "https://atomagentos.com/marketplace/components/comp-xyz789"
}

**Governance:**

• Requires marketplace permission (see above)
• Component must belong to tenant
• Tenant isolation: Enforced

---

Integration Canvas API

Visual workflow builder for connecting integrations.

Add Integration Node

**POST** /canvas/{canvas_id}/integrations

Add an integration node to canvas.

**Request Body:**

{
  "integration_id": "salesforce",
  "position": {"x": 100, "y": 200},
  "size": {"width": 300, "height": 200},
  "config": {
    "object_type": "Lead"
  },
  "display_name": "Salesforce Leads"
}

**Response:**

{
  "node_id": "node-abc123",
  "canvas_id": "canvas-xyz",
  "integration_id": "salesforce",
  "position": {"x": 100, "y": 200},
  "created_at": "2026-02-16T00:00:00Z"
}

**Governance:**

• Integration must be connected (valid token)
• Canvas must belong to tenant
• Tenant isolation: Enforced

---

WebSocket Connections

Real-time updates for canvas collaboration.

Canvas Actions WebSocket

**WS** /api/canvas/{canvas_id}/actions/ws

Real-time action proposals and approvals.

**Connection URL:**

wss://api.atomagentos.com/api/canvas/{canvas_id}/actions/ws?tenant_id={tenant_id}&token={jwt_token}

**Message Types:**

// Client → Server
{"type": "ping"}

// Server → Client
{"type": "pong", "timestamp": "2026-02-16T00:00:00Z"}

// Server → Client (new action proposal)
{
  "type": "action_proposed",
  "action_id": "action-abc123",
  "action_type": "execute_command",
  "description": "Run data reconciliation",
  "agent_id": "agent-xyz789"
}

// Client → Server (approve action)
{
  "type": "action_approved",
  "action_id": "action-abc123",
  "modified_data": {}
}

// Client → Server (reject action)
{
  "type": "action_rejected",
  "action_id": "action-abc123",
  "reason": "Too dangerous"
}

---

Canvas Terminal WebSocket

**WS** /api/canvas/{canvas_id}/terminal/{session_id}/ws

Real-time command output streaming.

**Connection URL:**

wss://api.atomagentos.com/api/canvas/{canvas_id}/terminal/{session_id}/ws?tenant_id={tenant_id}&token={jwt_token}

**Message Types:**

// Server → Client (output stream)
{
  "type": "output",
  "data": "line of output\n",
  "timestamp": "2026-02-16T00:00:00Z"
}

// Server → Client (command completed)
{
  "type": "completed",
  "exit_code": 0,
  "execution_time_ms": 45
}

// Server → Client (error)
{
  "type": "error",
  "message": "Command failed",
  "exit_code": 1
}

---

Integration Canvas WebSocket

**WS** /ws/canvas/{canvas_id}

Real-time canvas updates (nodes, connections).

**Connection URL:**

wss://api.atomagentos.com/ws/canvas/{canvas_id}?tenant_id={tenant_id}&token={jwt_token}

**Message Types:**

// Server → Client (node added)
{
  "type": "node_added",
  "node": {
    "id": "node-abc123",
    "integration_id": "salesforce",
    "position": {"x": 100, "y": 200}
  }
}

// Server → Client (connection created)
{
  "type": "connection_created",
  "connection": {
    "id": "conn-abc123",
    "source_node_id": "node-abc123",
    "target_node_id": "node-xyz789"
  }
}

---

Error Codes

**Error Response Format:**

{
  "error": "Governance Block",
  "detail": {
    "reason": "Agent maturity level 'student' cannot perform this action without approval",
    "agent_status": "student",
    "requires_human_approval": true
  }
}

---

Governance Rules

Agent Maturity Levels

**Student Agent:**

• Read-only canvas operations
• View terminal output (no command execution)
• View browser state (no navigation)
• All actions require approval

**Intern Agent:**

• Low-complexity operations
• Safe commands only (ls, cat, grep)
• View-only browser operations
• Most actions require approval

**Supervised Agent:**

• Medium-complexity operations
• Most terminal commands allowed
• Browser navigation and form filling
• High-risk actions require approval
• Live monitoring enabled

**Autonomous Agent:**

• All operations allowed
• Full command execution
• Full browser automation
• Can supervise other agents
• May still propose actions for transparency

Path Validation Rules

**Student/Intern:**

• No file system paths allowed

**Supervised:**

• /tmp directory
• User home directory
• .atom* paths

**Autonomous:**

• All paths except:
• /System/*
• /Windows/*
• /boot/*
• /etc/* (read-only)

Command Timeout

Default timeout: 30 seconds

Maximum timeout: 300 seconds (5 minutes)

---

Rate Limiting

• Free tier: 50 canvas operations per day
• Solo tier: 500 canvas operations per day
• Team tier: 5,000 canvas operations per day
• Enterprise: Custom limits

Rate limit headers:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1705401600

---

Troubleshooting

Issue: 401 Unauthorized

**Cause:** Missing or invalid JWT token

**Solution:**

1. Ensure Authorization: Bearer <token> header is present
2. Verify token is not expired
3. Check token has correct tenant_id

---

Issue: 403 Forbidden - Governance Block

**Cause:** Agent maturity level insufficient for action

**Solution:**

1. Check agent maturity level
2. Review action type and risk level
3. Ensure proper approval workflow for student/intern agents

---

Issue: WebSocket Connection Failed

**Cause:** Missing tenant_id or token in query parameters

**Solution:**

1. Include tenant_id in query params
2. Include valid JWT token in query params
3. Check WSS URL format: wss://host/path?tenant_id=X&token=Y

---

Issue: Component Installation Failed

**Cause:** Component not found or tenant mismatch

**Solution:**

1. Verify component_id is correct
2. Check component is published to marketplace
3. Ensure tenant has permission to install

---

SDK Examples

Python SDK

from atom_sdk import CanvasClient

client = CanvasClient(
    api_key="your-api-key",
    tenant_id="your-tenant-id"
)

# Create terminal session
session = client.create_terminal_session(
    canvas_id="canvas-xyz",
    working_directory="/tmp"
)

# Execute command
result = client.execute_command(
    canvas_id="canvas-xyz",
    session_id=session.id,
    command="ls -la"
)

print(result.stdout)

JavaScript SDK

import { CanvasClient } from '@atom/sdk';

const client = new CanvasClient({
  apiKey: 'your-api-key',
  tenantId: 'your-tenant-id'
});

// Browse marketplace
const components = await client.marketplace.browse({
  category: 'visualization',
  is_free: true
});

// Install component
const installation = await client.marketplace.install({
  componentId: 'comp-abc123',
  canvasId: 'canvas-xyz'
});

---

Changelog

v1.0.0 (2026-02-16)

• Initial Canvas API release
• 7 canvas route types documented
• WebSocket connections for real-time updates
• Governance enforcement for all maturity levels
• Tenant isolation across all endpoints
• Marketplace with component-skill pairing

---

Support

For issues or questions:

• Documentation: https://docs.atom.ai
• GitHub: https://github.com/atom/atom-saas
• Email: support@atom.ai